<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Summon &mdash; Golem v1.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '',
          VERSION:     '1.0',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: ''
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/interface.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html" />
    <link rel="index" title="Global index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Golem v1.0 documentation" href="index.html" />
    <link rel="next" title="Developing CML/Golem dictionaries" href="makingdictionaries.html" />
    <link rel="prev" title="Installing Golem" href="install.html" />
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="makingdictionaries.html" title="Developing CML/Golem dictionaries"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="install.html" title="Installing Golem"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section" id="summon">
<h1 id="summon">Summon<a class="headerlink" href="#summon" title="Permalink to this headline">¶</a></h1>
<p>Summon is a utility to enable researchers to extract data
from one or more CML files and collate the results as a comma-separated list
of data, one line per file.</p>
<div class="section" id="installing-summon">
<h2 id="installing-summon">Installing Summon<a class="headerlink" href="#installing-summon" title="Permalink to this headline">¶</a></h2>
<p>Summon is installed as part of Golem. If you have installed Golem using the
<tt class="docutils literal"><span class="pre">make</span></tt> approach outlined earlier, you&#8217;ll find <tt class="docutils literal"><span class="pre">summon</span></tt> in
<tt class="docutils literal"><span class="pre">/usr/local/bin</span></tt>; however, if you have used <tt class="docutils literal"><span class="pre">setup.py</span></tt> or
<tt class="docutils literal"><span class="pre">easy_install</span></tt>, you may need to add <tt class="docutils literal"><span class="pre">summon</span></tt> to your path.</p>
<p>For example, on OS X:</p>
<div class="highlight"><pre><span class="nv">$ </span>which summon
/opt/local/Library/Frameworks/Python.framework/Versions/2.4/bin/summon
</pre></div>
<p>Similarly, on Windows and Unix machines, the <tt class="docutils literal"><span class="pre">summon</span></tt> script will be
installed in your site-wide Python scripts directory (the same location where
<tt class="docutils literal"><span class="pre">easy_install</span></tt> is found) - typically <tt class="docutils literal"><span class="pre">C:\Python25\Scripts</span></tt></p>
</div>
<div class="section" id="note-for-windows-users">
<h2 id="note-for-windows-users">Note for Windows users<a class="headerlink" href="#note-for-windows-users" title="Permalink to this headline">¶</a></h2>
<p>Windows and Unix have different approaches to deciding what programs should be
executable; this makes it difficult to install the utilities which ship with
Golem as executables out-of-the-box. So, in the following examples, assuming
you&#8217;ve added your Python install directory to your path, please substitute:</p>
<div class="highlight"><pre>c:<span class="se">\m</span>ycmldata<span class="se">\&gt;</span> python c:<span class="se">\P</span>ython25<span class="se">\S</span>cripts<span class="se">\s</span>ummon
</pre></div>
<p>(again, assuming Python is installed in <tt class="docutils literal"><span class="pre">c:\Python25\</span></tt>; if it&#8217;s
installed somewhere else, substitute that path in too) for:</p>
<div class="highlight"><pre><span class="nv">$ </span>summon
</pre></div>
<p>when running the examples.</p>
</div>
<div class="section" id="using-summon">
<h2 id="using-summon">Using Summon<a class="headerlink" href="#using-summon" title="Permalink to this headline">¶</a></h2>
<p>Summon comes with a built-in help message:</p>
<pre>$ summon --help
usage: summon options file1.xml [file2.xml ...]

options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -t TERM, --term=TERM  terms to look up
  -d DICTIONARY, --dictionary=DICTIONARY
                        dictionary to use
  -c CONFIG, --config=CONFIG
                        config file to use
  -f, --final           take only last value in file?
  -o OUTFILE, --outfile=OUTFILE
                        dump output to csv file</pre>
<p>To explain how summon works, we start by taking an example.</p>
<div class="highlight"><pre><span class="nv">$ </span>summon -t numbers_of_species -d rmcprofileDict.xml ag3cocn6_300k.xml
</pre></div>
<p>Here, we&#8217;re extracting the numbers of the different atomic species in a
simulation (<tt class="docutils literal"><span class="pre">ag3cocn6_300k.xml</span></tt>), which is represented by the term
<tt class="docutils literal"><span class="pre">number_of_species</span></tt> in the CML/Golem dictionary <tt class="docutils literal"><span class="pre">rmcprofileDict.xml</span></tt>.
We cover the development of dictionaries later, but for now it&#8217;s sufficient
to know that a dictionary contains a list of terms and metadata on how
to locate and manipulate the data the terms refer to.</p>
<p>The result of this call will look something like:</p>
<div class="highlight"><pre>numbers_of_species
<span class="s2">&quot;[864, 288, 1728, 1728]&quot;</span>
</pre></div>
<p>where the line reflects the parameter name, and the 4 numbers are the counts
of the numbers of atoms of each of the four types in the simulation file (from
the name of the file you can guess that these are Ag, Co, C and N). To extract
multiple quantities at once, specify each separately using <tt class="docutils literal"><span class="pre">-t</span> <span class="pre">TERM</span></tt>, where
<tt class="docutils literal"><span class="pre">TERM</span></tt> is the <tt class="docutils literal"><span class="pre">id</span></tt> of the concept in the dictionary or Summon
configuration file; quantities from the same file will be written to the same
line in the output.</p>
<p>You can pass multiple XML files on the command line, in which case you get one
line of data per file. However, by itself, there&#8217;s no means to tell which line
corresponds with each file, and thus if you need this information, you will
need to ensure that you capture data that provides this unambiguous link.
Suppose we performed a large number of simulations using the <a class="reference external" href="http://www.esc.cam.ac.uk/ossia/">OSSIA</a> code, where each simulation corresponded
to a different temperature. If we want to extract the value of a quantity
called <tt class="docutils literal"><span class="pre">energy</span></tt> from each file, to plot it versus <tt class="docutils literal"><span class="pre">temperature</span></tt> (as
defined in <tt class="docutils literal"><span class="pre">ossiaDict.xml</span></tt>), and assuming the CML outputted by OSSIA is in
the current working directory, we would use the following summon command
containing multiple instances of the <tt class="docutils literal"><span class="pre">-t</span></tt> option:</p>
<div class="highlight"><pre><span class="nv">$ </span>summon -t temperature -t energy -d /PATH/TO/DICTIONARIES/ossiaDict.xml *.xml
</pre></div>
<p>As you can see, in practice we usually don&#8217;t need file names; just to know
that temperatures and energies match up. For instance, in this case we do know
that both temperature and energy for any simulation, which will be given on
the same line, will come from the same file.</p>
<p>Any term in a dictionary with a defined mapping from CML to a Golem
object can be extracted in this manner - basically, any entry that directly
contains, or is, a <tt class="docutils literal"><span class="pre">&lt;scalar&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;array&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;matrix&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;lattice&gt;</span></tt>,
<tt class="docutils literal"><span class="pre">&lt;atomArray&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;metadata&gt;</span></tt> or <tt class="docutils literal"><span class="pre">&lt;cellParameter&gt;</span></tt>. Concepts where this
mapping is not defined will raise an error. Looking in the dictionary, you
can spot these because they do not contain lines like:</p>
<div class="highlight"><pre><span class="nt">&lt;golem:template</span> <span class="na">call=</span><span class="s">&quot;scalar&quot;</span> <span class="na">role=</span><span class="s">&quot;getvalue&quot;</span> <span class="na">binding=</span><span class="s">&quot;pygolem_serialization &quot;</span><span class="nt">/&gt;</span>
</pre></div>
</div>
<div class="section" id="routing-output">
<h2 id="routing-output">Routing output<a class="headerlink" href="#routing-output" title="Permalink to this headline">¶</a></h2>
<p>To route output to a file as well as to the console, use the <tt class="docutils literal"><span class="pre">-o</span></tt> (or
<tt class="docutils literal"><span class="pre">--output=</span></tt>) option:</p>
<div class="highlight"><pre><span class="nv">$ </span>summon -t temperature -t energy -d ossiaDict.xml -o output.csv *.xml
</pre></div>
<p>This produces a CSV file, <tt class="docutils literal"><span class="pre">output.csv</span></tt>, ready to import into your favourite
spreadsheet.</p>
</div>
<div class="section" id="summon-configuration-files">
<h2 id="summon-configuration-files">Summon configuration files<a class="headerlink" href="#summon-configuration-files" title="Permalink to this headline">¶</a></h2>
<p>Some of the time, the concepts you wish to extract may not be directly
referenced within the CML/Golem dictionary for your code. This could be for a
number of reasons; maybe the concept is too specific to be incorporated in the
dictionary, such as a specific bond length in a system (which would only exist
in systems of that kind), or possibly markup for this concept has been
introduced recently into your code and the dictionary hasn&#8217;t been updated to
match yet. In that case, you may need to write a Summon configuration file in
order to define those concepts. Let&#8217;s say that the <tt class="docutils literal"><span class="pre">number_of_species</span></tt>
concept, used earlier, is missing from <tt class="docutils literal"><span class="pre">rmcprofileDict.xml</span></tt>; we therefore
need to supply a definition.</p>
<div class="section" id="writing-summon-configuration-files">
<h3 id="writing-summon-configuration-files">Writing Summon configuration files<a class="headerlink" href="#writing-summon-configuration-files" title="Permalink to this headline">¶</a></h3>
<p>We do that by adding entries to a configuration file (say,
<tt class="docutils literal"><span class="pre">rmcprofile.cfg</span></tt>):</p>
<div class="highlight"><pre><span class="o">[</span>numbers_of_species<span class="o">]</span>
<span class="nb">type</span>: array
xpath: //cml:parameterList/cml:parameter<span class="o">[</span>@dictRef<span class="o">=</span><span class="s2">&quot;rmcprofile:numbers_of_species&quot;</span><span class="o">]</span>
</pre></div>
<p>where the name of the concept is the first line (<tt class="docutils literal"><span class="pre">[numbers_of_species]</span></tt>),
the <tt class="docutils literal"><span class="pre">type</span></tt> of the data therein is <tt class="docutils literal"><span class="pre">array</span></tt> (taken from the list of types
Golem, and therefore <tt class="docutils literal"><span class="pre">summon</span></tt>, understands, as given earlier), and the
XPath expression which points to the bit of CML we want to extract is
<tt class="docutils literal"><span class="pre">xpath</span></tt>. (The CML namespace is defined to always be
<tt class="docutils literal"><span class="pre">http://www.xml-cml.org/schema</span></tt>, so you don&#8217;t need to worry about declaring
that). The fragment of CML that this refers to is:</p>
<div class="highlight"><pre><span class="nt">&lt;parameterList&gt;</span>
 <span class="nt">&lt;parameter</span> <span class="na">dictRef=</span><span class="s">&quot;rmcprofile:numbers_of_species&quot;</span> <span class="na">name=</span><span class="s">&quot;Numbers of each species&quot;</span><span class="nt">&gt;</span>
   <span class="nt">&lt;array</span> <span class="na">size=</span><span class="s">&quot;4&quot;</span> <span class="na">dataType=</span><span class="s">&quot;xsd:integer&quot;</span> <span class="na">units=</span><span class="s">&quot;cmlUnits:countable&quot;</span><span class="nt">&gt;</span>864 288 1728 1728<span class="nt">&lt;/array&gt;</span>
   <span class="nt">&lt;/parameter&gt;</span>
<span class="nt">&lt;/parameterList&gt;</span>
</pre></div>
<p>Thus, you can easily (effectively) define extra terms when you need them. If
you wish to rename or inherit terms from elsewhere - say, a dictionary that
came with Golem - then that is also possible. Again, using
<tt class="docutils literal"><span class="pre">numbers_of_species</span></tt> as an example, and assuming the <tt class="docutils literal"><span class="pre">rmcprofile</span></tt>
dictionary is available, you can define the term as follows.</p>
<div class="highlight"><pre><span class="o">[</span>numbers_of_species<span class="o">]</span>
dictRef: <span class="o">{</span>http://www.esc.cam.ac.uk/rmcprofile<span class="o">}</span>numbers_of_species
</pre></div>
<p>In general, <tt class="docutils literal"><span class="pre">dictRef</span></tt> consists of the namespace of the dictionary you wish
to use and the <tt class="docutils literal"><span class="pre">id</span></tt> of the term within that dictionary you want.
Alternatively, you can import entire dictionaries into your configuration with
the following declaration:</p>
<div class="highlight"><pre><span class="o">[</span>global<span class="o">]</span>
dictionary: /path/to/dictionary
</pre></div>
<p>This makes every term in the dictionary available in this configuration
file; in other words, it is exactly equivalent to entering into your
configuration file</p>
<div class="highlight"><pre><span class="o">[</span>term<span class="o">]</span>
dictRef: <span class="o">{</span>http://dictionary.namespace/<span class="o">}</span>term
</pre></div>
<p>for every entry in the dictionary. However, if you explicitly define a
term in the config file, that definition will be used <em>even if</em> it has
been loaded from a dictionary already. If a Summon configuration file
contains multiple <tt class="docutils literal"><span class="pre">[global]</span></tt> sections, and some of those dictionaries
contain the same term, then the first-loaded dictionary wins.</p>
</div>
<div class="section" id="using-summon-configuration-files">
<h3 id="using-summon-configuration-files">Using Summon configuration files<a class="headerlink" href="#using-summon-configuration-files" title="Permalink to this headline">¶</a></h3>
<p>Summon configuration files are used in the same way as dictionaries, except
that you load them with the <tt class="docutils literal"><span class="pre">-c</span></tt> command line option, not <tt class="docutils literal"><span class="pre">-d</span></tt>. For
example, using <tt class="docutils literal"><span class="pre">rmcprofile.cfg</span></tt> from earlier:</p>
<div class="highlight"><pre><span class="nv">$ </span>summon -t numbers_of_species -c rmcprofile.cfg ag3cocn6_300k.xml
</pre></div>
<p>will generate the same output as the dictionary-using approach given earlier.</p>
<p>In summary, Summon configuration files are a way of constructing new
CML/Golem dictionaries on the fly as you need them, without going to all the
effort of writing the XML by hand.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference external" href="">Summon</a><ul>
<li><a class="reference external" href="#installing-summon">Installing Summon</a></li>
<li><a class="reference external" href="#note-for-windows-users">Note for Windows users</a></li>
<li><a class="reference external" href="#using-summon">Using Summon</a></li>
<li><a class="reference external" href="#routing-output">Routing output</a></li>
<li><a class="reference external" href="#summon-configuration-files">Summon configuration files</a><ul>
<li><a class="reference external" href="#writing-summon-configuration-files">Writing Summon configuration files</a></li>
<li><a class="reference external" href="#using-summon-configuration-files">Using Summon configuration files</a></li>
</ul>
</li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="install.html" title="previous chapter">Installing Golem</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="makingdictionaries.html" title="next chapter">Developing CML/Golem dictionaries</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/summon.txt">Show Source</a></li>
            </ul>
            <h3>Quick search</h3>
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="makingdictionaries.html" title="Developing CML/Golem dictionaries"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="install.html" title="Installing Golem"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2008, Andrew Walkingshaw.
      Last updated on Oct 01, 2008.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>